Content

 Introduction
 Commands in Detail
 Functions to Transform Floating Point Numbers into Strings and Vice Versa

Introduction

The Extension Library expands the command set of Omikron Basic by commands that are not contained in the standard command set but that are required or at least useful for the creation of programs for the MacOS. In order to use the Extension Library it must be loaded into the program in the editor with the menu option 'Merge LIBRARY'. It is important to remember calling an 'Extension_Init' at the beginning of the program and an 'Extension_Exit' at its end.

Note: All functions without any postfix are of the long integer type (%L). If you have defined another default type in your editor, the postfix "%L" has to be added to the function names.

Commands in Detail

Extension_Init
This procedure must be called once before any other commands are used.

Extension_Exit
This procedure is called if use of the library functions has been concluded.

Error_Messages F
If an error occurs in your program during runtime (e.g., if an attempt was made to open a file that does not exist), an error message is then usually issued by Omikron Basic and output to an alert box. This behavior is certainly very useful during the program's development time - however, it is more likely rather disturbing once the program has been completed. For this reason, the output of error messages can be turned off with this procedure.

F=0 : Error messages off; otherwise, error messages on.

However, in case a fatal error occurs (e.g., if too little BASIC memory is available), which makes a continuation of the program impossible, Omikron Basic will always issue a message and terminate the program as well.

Set_Help(Tc)
This procedure defines, which key should be used for ON HELP GOSUB. The keyboard code must be applied for Tc. The default value is $69, which corresponds to function key 13 (F13). An overview of the keyboard codes can be found in "Inside Macintosh, Toolbox Essentials" and in the appendix 'Virtual Key Codes'.

Set_Sleep(S)
This procedure sets the sleep parameter, which Omikron Basic passes to the MacOS at every call of a WaitNextEvent (see also 'The Omikron Basic Output Windows' and 'New Compiler Control Words'). The sleep parameter determines how much CPU time will be allotted to other programs. The default value is 1; a higher number slows down the program, instead, however, this leaves more processor time for other programs running parallel.

Set_Tab(T)
This procedure sets the tabulator, which is used for PRINT and LPRINT. The default value is 8.

Fill_Input_Buffer(F$,C)
The INPUT buffer is loaded with the string F$, the cursor is set to position C, starting at the beginning of INPUT. This command makes it possible to pre-set an input value for INPUT statements, which must then only be confirmed with [Return] if necessary. Since the INPUT buffer is also used for other tasks, this procedure should always be called immediately before the actual INPUT command.

FN Get_Created_Dirid
If a new directory is created using MKDIR, the identification number of this directory may be received if this function is called directly afterwards.

Get_Def_Dir(R Vrefnum%,R Dirid,R Volname$,R Errnum)
This procedure returns the volume reference number, the directory identification number, and the volume name of the default path. If necessary, Errnum contains an error number.

Get_Cur_Dir(R Vrefnum,R Dirid)
This procedure returns the volume reference number and the directory identification number of the current path.

Get_System_Folder(Type,R Vrefnum,R Dirid,R Os_Err)
This procedure serves to determine the volume reference number and the directory identification number of the system folder and all subfolders in the system folder.
The folder type has to be passed in Type. The following elements are possible:

Type = CVIL("amnu") : Apple Menu Items
Type = CVIL("ctrl") : Control Panels
Type = CVIL("Desk") : Desktop Folders
Type = CVIL("extn") : Extensions
Type = CVIL("font") : Fonts Folder
Type = CVIL("pref") : Preferences Folder
Type = CVIL("prnt") : Print Monitor Documents
Type = CVIL("strt") : Startup Items
Type = CVIL("macs") : System Folder
Type = CVIL("temp") : Temporary Items
Type = CVIL("trsh") : Single User Trash
Type = CVIL("empt") : Shared Trash on Net

Os_Err may have the following values when returned:

Os_Err=0 : No error.
Os_Err=-43 : The indicated type was not found.
Os_Err=-48 : A file was found instead of a folder.

FN Get_Vrefnum(Fsspec$)
This function returns the volume reference number if a FileSpecificationRecord is passed.

FN Get_Dirid(Fsspec$)
This function returns the directory identification number if a FileSpecificationRecord is passed.

FN Get_Filename$(Fsspec$)
This function returns the file name if a FileSpecificationRecord is passed.

FN Get_Font_Number(Name$)
This function returns the number of a font if its name has been passed to the function (e.g., Monaco, Courier, VT100).

FN Get_Fsspec$(Vrefnum,Dirid,Filename$)
If a volume reference number, a directory identification number, and a file name is passed to this function, such a FileSpecificationRecord is returned as it is e.g., needed for OPEN. Vrefnum and Dirid can also be zero. However, in that case Filename$ can either contain a complete path or a partial path with a preceeding colon or a pure file name without a preceeding colon, with the latter two considered to be based on the current path. Thus, if you pass a partial path you have to write a colon in front of all other characters.

FN Get_File_Count
With this function it is possible to find out, how many bytes have actually been read or written, for example, in the case of PUT or GET.

FN Get_File_Type(Fsspec$)
This function returns the file type (e.g., "TEXT", "PICT" ...) of the file specified by Fsspec$. The result of this function is a long integer number. In order to receive a string, the BASIC function MKIL$ has to still be applied to the long integer number

FN Get_File_Creator(Fsspec$)
This function returns the file creator (e.g., "OmBa" ...) of the file specified by Fsspec$. The result of this function is a long integer number. In order to receive a string, the BASIC function MKIL$ has to still be applied to the long integer number.

FN Get_Finder_Flags(Fsspec$)
This function can be used to determine which finder flags have been set using the file specified by Fsspec$. Most of the finder flags are used internally. Thus, only those flags are listed below, which are of interest for the programmer and may be modified as well. Those programmers who would like to know more about the significance of the remaining flags, please read the appropriate sections in  "Inside Macintosh, Toolbox Essentials."

Bit 14 : The file is invisible, thus it is displayed neither on the desktop nor in the file select box.
Bit 13 : The file has a "BNDL" resource. Such a resource is required to assign specific icons to the files.
Bit 12 : Neither the icon nor the name can be modified from the Finder.
Bit 11 : The file is a so-called "stationery pad."  To describe this term in more details would surpass the available space here. More details can be found in "Inside Macintosh, Toolbox Essentials."
Bit 10 : The file has a "customized icon."
Bit 6 : The file is a program, which can be used simultaneously by several users within a network.

Note: The finder flags can also be applied to directories. Insofar as the result might not have any practical significance, these finder flags should be considered reserved and thus not be modified.  

Set_File_Type([Fsspec$,]Filetype)
When creating a new file (e.g., using OPEN "O"), the file type number, which was previously set using this procedure, is assigned to the file. For example, Set_File_Type(CVIL("TEXT") causes all subsequently created files to be of the type 'TEXT', that is, they are pure ASCII files. The appendix lists the most important pre-defined file types.
When using a syntax with 2 parameters, it is possible to pass a FileSpecificationRecord in Fsspec$, which then modifies the type of the file thusly determined.
A more detailed description of the previously mentioned terms can be found in "InsideMacintosh, Files."

Set_File_Creator([Fsspec$,]Creator)
When creating a new file (e.g., using OPEN "O"), the CreatorIdentificationNumber, which was previously set using this procedure, is assigned to the file. 
When using a syntax with 2 parameters, it is possible to pass a FileSpecificationRecord in Fsspec$, which then modifies the creator of the thusly determined file.

Set_Finder_Flags(Fsspec$,Flags)
This procedure allows the modification of the so-called finder flags. This requires that a FileSpecificationRecord is passed in Fsspec$, which specifically determines the file containing the to be modified flags. The significance of the indivdual bits is described under FN Get_Finder_Flags.

FN Get_Quick_Draw
This function returns a pointer to the QuickDrawGlobals. "Inside Macintosh, Imaging with QuickDraw " features a precise description of this structure.

FN Get_G_World_Ptr
This function returns a pointer to the offscreen graphics world used for buffering the uppermost output window of Omikron Basic. The structure is described in " Inside Macintosh, Imaging with QuickDraw."

FN Get_G_World_Ptr(S)
This function returns a pointer to the offscreen graphics world used for buffering the output window of Omikron Basic, which has been opened with SCREEN S. The structure is described in "Inside Macintosh, Imaging with QuickDraw."

FN Get_Window_Ptr
This function returns a pointer to the window pointer of the output window of Omikron Basic, which has been opened with SCREEN S. The structure is described in " Inside Macintosh, Imaging with QuickDraw."

Get_Window_Offset(Screen_Nr,R X_Offset,R Y_Offset)
If you are working with Omikron Basic output windows and would like to directly output to the real windows, you have to know which part of the virtual screen buffered in memory is currently displayed in the window because this is dependent on the position of the scroll bars.
The procedure Get_Window_Offset calculates the offset using the position of the scroll bars, which is assigned to the left, upper inside corner of the real window on the virtual screen and returns these values in X_Offset and Y_Offset.

Set_Window_Title(T$)
This procedure sets the title of the uppermost Omikron Basic output window to T$.

Get_Indexed_Color(Index,R Red,R Green,R Blue)
This procedure returns the red, green, and blue components of a color from the internal Omikron Basic color map, whose index is passed. Red, green and blue can take values between 0 and 65535.#

Set_Indexed_Color(Index,Red,Green,Blue)
This procedure sets the red, green, and blue component of a color in the internal Omikron Basic color map, whose index is passed. Red, green, and blue must have values between 0 and 65535.

Set_Pen_Size(Width,Height)
This procedure sets the width and height of the drawing pen used e.g., for DRAW or BOX. It corresponds to LINE WIDTH except that in this case, width and height can take different values.

Set_Roundings(X,Y)
This procedure defines the rounding of the corners during use of RBOX and PRBOX. X and Y are the semi-axes of an ellipse being adapted to the rounding.

Set_Scroll_Parameter(X,Y)
This procedure defines the number of the pixels by which the content of the output windows is to be moved when clicking on the scroll arrows. X represents the horizontal and Y the vertical direction. The default setting is 8 for X and 16 for Y.

Set_Text_Mode(Mode)
This procedure sets the linking mode as used in the case of MODE, only difference is that this procedure is especially for TEXT commands.

Set_Text_Size(Size)
This procedure corresponds to the command TEXT HEIGHT, thus adjusts the size of characters output with the TEXT commands.

Set_Text_Font(Font_No)
This procedure selects the font to be used for TEXT commands.

Set_Text_Face(Face)
This procedure corresponds to the command TEXT STYLE, thus adjusts the font style of characters output with the TEXT commands.

Set_Text_Fore_Color(Index)
This procedure corresponds to the command TEXT COLOR, thus sets the display foreground color used for TEXT commands to the color assigned to the index.

Set_Text_Back_Color(Index)
This procedure sets the background color used for TEXT commands to the color assigned to the index.

Set_Print_Mode(Mode)
This procedure sets the linking mode the same way as in the case of MODE, only difference is that this procedure is especially for PRINT and INPUT commands.

Set_Print_Size(Size)
This procedure sets up the size for those characters that are output with PRINT and INPUT commands.

Set_Print_Font(Font_No)
This procedure selects the font to be used for PRINT and INPUT commands.

Caution: The PRINT and INPUT commands function only correctly if non-proportional fonts are being used, that is, fonts where all letters are equally wide. For all the existing default fonts, this is true only for ''Monaco (Font_No=4)' and 'Courier (Font_No=22)''. Starting with system 7.6, 'VT100' is still available as well.

Set_Print_Face(Face)
This procedure approximately corresponds to the command TEXT STYLE. However, the setting is only valid for PRINT and INPUT commands.

Set_Print_Fore_Color(Index)
This procedure sets the foreground color used for PRINT and INPUT commands to the color assigned to the index.

Set_Print_Back_Color(Index)
This procedure sets the background color used for PRINT and INPUT commands to the color assigned to the index.
Note: This command can also be used to set the background color for the Omikron Basic output windows.

Set_Lprint_Mode(Mode)
This procedure sets the linking mode the same way as in the case of MODE, only difference is that this procedure is especially for LPRINT commands.

Set_Lprint_Size(Size)
This procedure adjusts the size of characters output with the LPRINT commands.

Set_Lprint_Font(Font_No)
This procedure selects the font to be used for LPRINT commands.

Caution: The PRINT and INPUT commands function only correctly if non-proportional fonts are being used, that is, fonts where all letters are equally wide when tabulator functions are being used. For all the existing default fonts, this is true only for ''Monaco (Font_No=4)' and 'Courier (Font_No=22)''. Starting with system 7.6, 'VT100' is still available as well.

Set_Lprint_Face(Face)
This procedure approximately corresponds to the command TEXT STYLE. However, the setting is only valid for PRINT and INPUT commands.

Set_Lprint_Fore_Color(Index)
This procedure sets the foreground color used for LPRINT commands to the color assigned to the index.

Set_Lprint_Back_Color(Index)
This procedure sets the background color used for LPRINT commands to the color assigned to the index.

Lprstldialog(R Button)
This procedure calls the dialog box 'PrStlDialog' of the printer driver. If the box was exited with OK, Button=1, otherwise 0. The possibility to call this dialog box should be incorporated into the program, otherwise any subsequent printouts will use only the unspecified default values.

Lprjobdialog(R Button)
This procedure calls the dialog box 'PrJobDialog' of the printer driver. If the box was exited with OK, Button=1, otherwise 0. This dialog box should be called unconditionally before every printout since the user still has the opportunity to adjust important settings in this dialog box. For example, which pages should even be printed, whether a preview is requested (not possible for every printer), which resolution should be used for the printout, and a few additional preference settings.

FN Microseconds#
This function returns the time, elapsed since system start up. Note, that this function is of type double float. It is similar to the BASIC function TIMER, but allows time measurements of much higher pecision, because the counter is incremented every millionth second instead of every 1/200.

FN Ser_Get_Buf (Channel)
This function returns the number of characters available in the buffer of the serial port. The channel has to be opened previously via OPEN "P",Channel and/or OPEN "V",Channel.

Ser_Reset (Channel,In_Out,Baud,Parity,Data_Bits,Stop_Bits)
This procedure allows the configuration of the serial port, which has been opened previously via OPEN "P",Channel and/or OPEN "V",Channel.

In_Out determines, whether the settings should be made for input or output:
In_Out=1 : output
In_Out=2 : input
In_Out=3 : output and input


Baud specifies the data transfer rate (bits per second). The following values are possible: 300,600,1200,1800,2400,3600,4800,7200,9600,14400,19200,28800,38400, and 57600.

For Parity three figures are allowed:
0 = no parity
1 = odd parity
2 = even parity

Data_Bits determines, how many data bits are sent at a time and may have values from 5 to 8.

With Stop_Bits you can determine the number of stop bits:
10 = 1 stopbit
15 = 1.5 stopbits
20 = 2 stopbits

FN Get_Scrap$(Type)
This function can be used to import data from the clipboard. You have to indicate the type of data in Type. For example: Txt$= FN Get_Scrap$(CVIL("TEXT")) would import a piece of text from the clipboard, as long as the clipboard contains data that is of type "TEXT". Of course, you may use this function to import more than just text such as pictures, for example ("PICT"). The data are always returned in a string. If the data is needed to be stored in a memory block you can copy the data to this block using the procedure String_To_Memory(Txt$,Mem_Adr).

Put_Scrap(Type,Txt$)
This procedure makes it possible to transfer any data located in the string Txt$ to the clipboard. You have to indicate the type of data in Type (e.g., simple ASCII texts = "TEXT" or pictures in the Apple picture format = "PICT"). Put_Scrap(CVIL("TEXT"),"sample text"), for example, would write the sample text to the clipboard; once there, other programs could import the sample text. If data should be located in a memory block, you can transfer them to a string using the function Txt$= FN Memory_To_String$(Mem_Adr,Length).

FN Memory_To_String$(Mem_Adr,Length)
This function copies data to a string, which is located in memory starting at Mem_Adr and have the length Length , and returns the string as a function value.

String_To_Memory(Txt$,Mem_Adr)
This procedure copies data located in the string Txt$ to memory starting at Mem_Adr.

Warning: You have to make absolutely sure that the memory block starting at Mem_Adr is sufficiently large enough to hold the entire string; otherwise, your computer will probably crash quite severely.

FN Get_Front_Process#
An 8-byte number is returned, the so-called ProcessSerialNumber. This number unambiguously identifies a running process. Please note that the function is of double float type. If you were to call this function right at the beginning of your program, the ProcessSerialNumber of your own program will be returned. You may use this number, e.g., to apply FN Get_Process_Path$(Psn#) to determine the path from which the program has been started. This information is important if you want to load additional data from the program path later. For example, this is how Omikron Basic finds the file NEWOMBAS.INF. By comparing the current Psn# with the one of your program, you can also find out at any time whether your program is currently in the foreground and then activate or deactivate certain activities (e.g., blinking cursor if the program is located in the background).

Set_Front_Process(Psn#)
A ProcessSerialNumber (Psn#) of an already running program has to be passed to this procedure. This program will then become the front process. If one's own program runs in the background because, for example, it is working on a complicated and time-consuming problem, and an error occurs, which requires some type of action by the user, then you can use this command to make your program the process running in the foreground.

FN Get_Process_Path$(Psn#)
A FileSpecificationRecord is returned, which indicates where on the hard drive the program with the ProcessSerialNumber(Psn#) is located. This information may be used, e.g., to load certain specific, additional data from the program folder.

Functions to Transform Floating Point Numbers into Strings and Vice Versa

The floating point number format, which was used by Omikron Basic for Atari computers differs from the one used for the PowerPC. In order to avoid a continual format conversion accompanied by the corresponding performance loss, the new Omikron Basic was changed to correspond to the PowerPC format (see also the chapter 'Differences Compared to the Atari Version').

In order to facilitate the conversion of older programs, there are four functions in the Extension Library, which emulate the behavior of the old Omikron Basic functions.

FN CVS#(Single$)
These function converts a 6-byte string of the old format into a double floating number.

Caution: Since the new format has a lesser value range than the old, errors may occur in the case of very small and/or very large numbers.

FN CVD#(Double$)
These function converts a 10-byte string of the old format into a double floating number.

Caution: Since the new format has a lesser value range than the old, errors may occur in the case of very small and/or very large numbers.

FN MKS$(Number)
This function converts a number into a 6-byte long string of the old format.

FN MKD$(Number)
This function converts a number into a 10-byte long string of the old format.